Skip to content

feat: embed lyrics into MP3 ID3 tags - #15

Merged
ByteMe6 merged 1 commit into
masterfrom
feature/embedded-lyrics
Nov 16, 2026
Merged

ByteMe6 merged 1 commit into
masterfrom
feature/embedded-lyrics

Conversation

@ByteMe6

@ByteMe6 ByteMe6 commented Nov 16, 2026

Copy link
Copy Markdown
Owner

Summary

Adds optional lyrics embedding for MP3 output. Lyrics are fetched from LRCLIB and written directly into the MP3 ID3 tag, so players can show words offline without sidecar .lrc/.txt files.

  • Plain lyrics go to USLT.
  • Synchronized LRC lyrics go to SYLT, with timestamps converted to milliseconds.
  • When timed lyrics exist, both frames are written. USLT keeps the full text for players without SYLT support.
  • Plain-only results produce only USLT; timestamps are never invented.
  • Existing USLT/SYLT frames are replaced, not duplicated.
  • Missing lyrics, timeouts and server errors never fail the download.
  • Existing tags, cover art and audio data are preserved; no audio re-encoding.
  • If an MP3 already has lyrics and no new lyrics are found, the existing frames are left untouched.

Configuration

  • CLI: --lyrics / --no-lyrics
  • Config: lyrics_enabled = true|false
  • Default: enabled for MP3. M4A and Opus output are unchanged.

Tests

Added coverage for:

  • USLT and SYLT write/read round-trips.
  • Simultaneous USLT + SYLT.
  • Cyrillic, Unicode and special characters.
  • Preservation of existing tags, comments and artwork.
  • Re-writing without duplicate frames.
  • Missing/empty lyrics without empty frames or failed downloads.
  • Preserving previously embedded lyrics when no new lyrics are found.
  • Audio payload remaining byte-identical.
  • CLI/config enable/disable precedence and invalid config values.

410 passed, ruff check clean.

Documentation updated in all three READMEs, CHANGELOG and the tldr page.

Fetch plain and synchronized lyrics from LRCLIB and write them to USLT
and SYLT. Both frames are written when timed lyrics exist, while plain-only
results produce only USLT. Missing lyrics or lookup errors never fail a
download, and existing tags, artwork, audio data and previously embedded
lyrics are preserved.

Add --lyrics/--no-lyrics and the lyrics_enabled config key. The feature is
enabled by default for MP3 and does not affect M4A or Opus output.
@ByteMe6
ByteMe6 merged commit bc4c851 into master Nov 16, 2026
9 checks passed
@ByteMe6
ByteMe6 deleted the feature/embedded-lyrics branch November 16, 2026 08:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant